/** 
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation. 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit. 
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement. 
 * Without SDK license agreement, you cannot redistribute anything.
 * Functions in this header file, require "FGSPDFFORMFILL" module to be enabled in your SDK license.
 *
 * @file	fpdfformfill.h
 * @brief	Header file for the Form Field module.
 * @details	The form field module offers methods which implement the following functions:
 *			1. Support to manually fill a PDF form.<br>
 *			2. Support to execute javascript by forms.<br>
 *			3. Allow setting or retrieving field values of a form from applications.<br>
 *			4. Support to export the content of a form to a XML file and import the XML file into the form as well.<br>
 *			<br>
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling Form Field module explicitly. 
 */

/** 
 * addtogroup FGSPDFFORMFILL PDF Form Field
 * @brief Definitions and Methods in this module are included in fpdfformfill.h.
 */

 /** @{*/
#ifndef __FGSPDFFORMFILL__
#define __FGSPDFFORMFILL__

#include "fpdfbase.h"
#include "fpdffwlevent.h"

#define FS_FORMFILL_KEY 10000

#ifdef __cplusplus
extern "C" {
#endif

/** 
 * @name FGSPDFFORMFILL Enumeration Types
 */
/**@{*/
/**
 * @brief Enum Definitions for Cursor Type.
 */
enum {
    /** Cursor Type: Arrow. */
    kPDFPDFCursorArrow             = 0,
    /** Cursor Type: NESW. */
    kPDFPDFCursorNESW              = 1,
    /** Cursor Type: NWSE. */
    kPDFPDFCursorNWSE              = 2,
    /** Cursor Type: Vertical Beam. */
    kPDFPDFCursorVBeam             = 3,
    /** Cursor Type: Horizontal Beam. */
    kPDFPDFCursorHBeam             = 4,
    /** Cursor Type: Hand. */
    kPDFPDFCursorHand              = 5,
};
/** @brief Alias of enumeration for cursor type. */
typedef UInt32 FGSPDFCursorType;
/**@}*/

/** 
 * @brief Definitions for print Flags. 
 */
/** @{*/
/** @brief the cancel dialog box will be suppressed while the document is printing. */
#define kFGSPDFPRINTFSILENT             1 << 0
/** @brief the page is shrunk (if necessary) to fit within the imageable area of the printed page. */
#define kFGSPDFPRINTFSHRINKTOFIT        1 << 1
/** @brief it will print pages as an image. */
#define kFGSPDFPRINTPRINTASIMAGE        1 << 2
/** @brief it will print from <i>nEnd</i> to <i>nStart</i>.*/
#define kFGSPDFPRINTFREVERSE            1 << 3
/** @brief annotations will be printed. */
#define kFGSPDFPRINTFANNOTATIONS        1 << 4
/**@}*/

/** @brief Structure for formfill information. */
typedef struct  __FGSPDFDocProvider
{
    /** @brief The size of the data structure. It must be set to <b>sizeof</b>(::FPDF_FORMFILL_INFO). */
    SInt32		size; 
    
    /** @brief The user-supplied data. */
    void *		clientData;
    
    /**
	 * @brief	Get the file path of the current document. 
	 *
	 * @param[in] clientData	The user-supplied data.
	 * @param[in] doc			Reference to  the annotation document.
	 *
	 * @return	The string buffer used to receive the file path. It can be <b>NULL</b>.
	 */
    CFStringRef	(*getFilePath)(void *clientData, FGSPDFDocumentRef doc);

    /** 
     * @brief Invalidate the client area within the specified rectangle.
     *
     * @details All positions are measured in PDF user space.
     *			Implementation should call ::FPDFPageStartRenderingPage function for repainting a specified page area.
     *
     * @param[in] clientData	Pointer to the interface structure itself.
     * @param[in] page			Reference to a PDF page.
     * @param[in,out] rect		The position of the client area in PDF page coordinate.
     *
     * @return None.
     *
     */
    void (*invalidate)(void *clientData, FGSPDFPageRef page, CGRect *rect);

    /** 
     * @brief Set the Cursor shape.
     *
     * @param[in] clientData	Pointer to the interface structure itself.
     * @param[in] nCursorType	Cursor type. see Definations of <b>FGSPDFCursorType</b>for the details.
     *
     * @return 		None.
     */
    void (*setCursor)(void *clientData, FGSPDFCursorType nCursorType);

    /** 
     * @brief This method will be invoked to notify implementation when the value of any FormField on the document had been changed.
     *
     * @details In some cases, the document-level JavaScript action may refer to a page which hadn't been loaded yet.
     *		To successfully run the javascript action, implementation need to load the page for SDK.
     *
     * @param[in] clientData	Pointer to the interface structure itself.
     * @param[in] document		Reference to a PDF document.
     *
     * @return None.
     */
    void (*onContentChange)(void *clientData, FGSPDFDocumentRef doc);

    /** 
     * @brief This method receives currently rotation of the page view.
     *
     * @param[in] clientData	Pointer to the interface structure itself.
     * @param[in] document		Reference to a PDF document.
     *
     * @return	The page rotation. This should be:(in a clockwise direction)<br>
     *			<ul>
     *			<li>0: 0 degree</li>
     *			<li>1: 90 degree</li>
     *			<li>2: 180 degree</li>
     *			<li>3: 270 degree</li>
     *			</ul>
     */
    SInt32 (*getRotation)(void *clientData, FGSPDFDocumentRef doc);
    
    /** 
     * @brief This method will execute an named action.
     *
     * @details See the named actions description of <<PDF Reference, version 1.7>> for more details.  
     *
     * @param[in] clientData	Pointer to the interface structure itself.
     * @param[in] namedAction	A byte string which indicates the named action, terminated by 0.
     *
     * @return None.
     */
    void (*executeNamedAction)(void *clientData, CFStringRef namedAction);
    
    /** 
     * @brief This method will be called when the focus is set to a formfield.
     *
     * @param[in] clientData	Pointer to the interface structure itself.
     * @param[in] field			Reference to the form field.
     * @param[in] focusText		The text on the focus.
     *
     * @return None.
     *
     * @note Currently,only support text field and combobox field.
     */
    void (*onSetFieldInputFocus)(void *clientData, FGSPDFFormFieldRef field, CFStringRef focusText);
    
    /** 
     * @brief This method receives the current page pointer.
     *
     * @param[in] clientData	Pointer to the interface structure itself.
     * @param[in] document		Reference to a PDF document.
     *
     * @return Reference to a PDF page.
     */
    FGSPDFPageRef (*getCurrentPage)(void *clientData, FGSPDFDocumentRef document);
    
    /** 
	 * @brief This method receives the page pointer associated with a specified page index.
	 *
	 * @details In some cases, the document-level JavaScript action may refer to a page which hadn't been loaded yet.
	 *		To successfully run the javascript action, implementation need to load the page for SDK.
	 *
	 * @param[in] clientData	Pointer to the interface structure itself.
	 * @param[in] doc			Specified document.
	 * @param[in] pageIndex  	Index number of the page. 0 for the first page.
	 *
	 * @return Reference to a PDF page.
	 */
	FGSPDFPageRef (*getPage)(void *clientData, FGSPDFDocumentRef document, SInt32 pageIndex);

    /** 
     * @brief Pop up a dialog to show warnings or hints.
     *
     * @param[in] clientData	The user-supplied data.
     * @param[in] Msg			A string containing the message to be displayed.
     * @param[in] Title			The title of the dialog.
     * @param[in] Type			The type of button group. Its value can be:
     *							<ul>
     *							<li>0: OK,(default value);</li>
     *							<li>1: OK, Cancel;</li>
     *							<li>2: Yes, NO; </li>
     *							<li>3: Yes, NO, Cancel.</li>
     *							</ul>
     * @param[in] Icon			The Icon type. Its value can be: 
     *							<ul>
     *							<li>0: Error,(default value);</li>
     *							<li>1: Warning;</li>
     *							<li>2: Question;</li>
     *							<li>3: Status.</li>
     *							</ul>
     *
     * @return	The return value could be the following type:
     *			<ul>
     *			<li>1: OK;</li>
     *			<li>2: Cancel;</li>
     *			<li>3: NO;</li>
     *			<li>4: Yes;</li>
     *			</ul>
     */
    SInt32 (*alert)(void *clientData, CFStringRef Msg, CFStringRef Title, SInt32 Type, SInt32 Icon);

    /** 
     * @brief	Cause the system to play a sound. 
     *
     * @param[in] clientData	The user-supplied data.
     * @param[in] nType			The sound type. Its value can be:
     *							<ul>
     *							<li>0: Error;</li>
     *							<li>1: Warning;</li>
     *							<li>2: Question;</li>
     *							<li>3: Status;</li>
     *							<li>4: Default (default value);</li>
     *							</ul>
     *
     * @return	None.
     */
    void (*beep)(void *clientData, SInt32 nType);

    /** 
     * @brief	Display a dialog box containing a question and an entry field for the user to reply to the question.  
     *
     * @details	No matter on what platform, the response should be always input in UTF-16LE encoding.
     *			The return value always indicates count of bytes required for the buffer, even when there is
     *			no buffer specified, or the buffer size is less then required. In this case, the buffer will not
     *			be modified.
     *
     * @param[in] clientData	The user-supplied data.
     * @param[in] Question		The question to be posed to the user.
     * @param[in] Title			The title of the dialog box.
     * @param[in] Default		A default value for the answer to the question. 
     *							If the answer is not specified, no default value is presented.
     * @param[in] cLabel		A short string to appear in front of the edit text field. 
     * @param[in] bPassword		<b>TRUE</b> means that the user's response should show as asterisks (*) or bullets (?) 
     *							to mask the response, which might be sensitive information. <br>
     *							The default is <b>FALSE</b>.
     *
     * @return	A string buffer used to receive the user's response. It can be <b>NULL</b>.
     */
    CFStringRef (*response)(void *clientData, CFStringRef Question, CFStringRef Title, CFStringRef Default, 
                          CFStringRef cLabel, Boolean bPassword);
    
    /*
	 * @brief	Show a file selection dialog, and return the selected file path.
	 *
	 * @param[in] clientData	The user-supplied data.
	 * @param[in] type			The type of file dialog.
	 *
	 * @return	The filePath should be always inputted in the local encoding.
	 *

	 */
    CFStringRef (*browse)(void *clientData, SInt32 type);
    
    /**
	 * @brief	Mail the data buffer as an attachment to all recipients, with or without user interaction. 
	 *
	 * @param[in] clientData	The user-supplied data.
	 * @param[in] doc			Reference to  the annotation document.
	 * @param[in] mailType		The mail type.
	 * @param[in] bUI			<b>TRUE</b> means that the rest of the parameters are used in a compose-new-message window 
	 *							which is displayed to the user.<br>
	 *							<b>FALSE</b> means that the parameter <i>To</i> is required and all others are optional.
	 * @param[in] To			A semicolon-delimited list of recipients for the message.
	 * @param[in] Subject		The subject of the message. The limit of the length is 64 KB.
	 * @param[in] CC			A semicolon-delimited list of CC recipients for the message. 
	 * @param[in] BCC			A semicolon-delimited list of BCC recipients for the message. 
	 * @param[in] Msg			The content of the message. The limit of the length is 64 KB.
	 *
	 * @return	None.
	 *
	 */
    void (*mail)(void *clientData, FGSPDFDocumentRef doc, SInt32 mailType, Boolean bUI, CFStringRef To, CFStringRef Subject, CFStringRef CC, CFStringRef BCC, CFStringRef Msg);
    
    /**
	 * @brief	Print all or a specific number of pages of the document.
	 *
	 * @param[in] clientData	The user-supplied data.
	 * @param[in] doc			Reference to  the annotation document.
     * @param[in] isUI			<b>TRUE</b> means that a UI will be presented to the user to obtain printing information and confirm the action.
	 * @param[in] nStart		A zero-based index of the start of an inclusive range of pages.
	 * @param[in] nEnd			A zero-based index of the end of an inclusive page range.
	 * @param[in] flags			The print flags.
	 *
	 * @return	None.
	 */
	void (*print)(void *clientData, FGSPDFDocumentRef doc, Boolean isUI, SInt32 nStart, SInt32 nEnd, SInt32 flags);

    /**
	 * @brief	Send the form data to a specified URL.
	 *
	 * @param[in] clientData	The user-supplied data.
	 * @param[in] doc			Reference to  the annotation document.
	 * @param[in] URL			The URL, to which the form data will be sent.
	 *
	 * @return	None.
	 */
	void (*submitForm)(void *clientData, FGSPDFDocumentRef doc, CFDataRef data, CFStringRef URL);

} FGSPDFDocProvider;

/**
 * @brief Init form fill environment. 
 *
 * @details This function should be called before any form fill operation.
 *
 * @param[in]  document			Reference to a PDF document.
 * @param[in]  platform			Pointer to a <b>::FGSPDFJSPlatForm</b> structure.
 * @param[out] docProvider		Pointer to a <b>::FGSPDFDocProvider</b> structure.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSPDFFormEnvRef FGSPDFFormFillInitEnvironment(FGSPDFDocumentRef document, FGSPDFDocProvider *docProvider);

/**
 * @brief This method is required for implementing all the form related functions. Should be invoked after user 
 *			successfully loaded a PDF page, and method ::FPDF_FormFill_InitEnvironment had been invoked.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] page				Reference to a PDF page.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillOnAfterLoadPage(FGSPDFDocumentRef document, FGSPDFPageRef page);
    
/**
 * @brief This method is required for implementing all the form related functions. Should be invoked before user 
 *			close the PDF page.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] page				Reference to a PDF page.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillOnBeforeClosePage(FGSPDFDocumentRef document, FGSPDFPageRef page);
    
/**
 * @brief This method is required for performing Document-level JavaScript action. It should be invoked after the PDF document
 *		  had been loaded.
 *
 * @details If there is Document-level JavaScript action embedded in the document, this method will execute the javascript action;
 *			otherwise, the method will do nothing.
 *
 * @param[in] document			Reference to a PDF document.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillDoDocumentJSAction(FGSPDFDocumentRef document);
    
/**
 * @brief This method is required for performing open-action when the document is opened.
 *
 * @details This method will do nothing if there is no open-actions embedded in the document. 
 *
 * @param[in] document			Reference to a PDF document.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillDoDocumentOpenAction(FGSPDFDocumentRef document);

/** 
 * @name FGSPDFFORMFILL Enumeration Types
 */
/**@{*/
/**
 * @brief Enum Definitions for Additional Action Types of Document.
 */
enum {
    /** WC, before closing document, JavaScript action. */
    kFGSPDFDocAActionWC             = 0x10,
    /** WS, before saving document, JavaScript action. */
    kFGSPDFDocAActionWS             = 0x11,
    /** DS, after saving document, JavaScript action. */
    kFGSPDFDocAActionDS             = 0x12,
    /** WP, before printing document, JavaScript action. */
    kFGSPDFDocAActionWP             = 0x13,
    /** DP, after printing document, JavaScript action. */
    kFGSPDFDocAActionDP             = 0x14,
};
/** @brief Alias of enumeration for additional action types of document. */
typedef UInt32 FGSPDFDocAActionType;
/**@}*/

/**
 * @brief This method is required for performing the document's additional-action.
 *
 * @details This method will do nothing if there is no document additional-action corresponding to the specified aaType.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] aaType			The additional action type of a document. See definitions <b>FGSPDFDocAActionType</b>.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillDoDocumentAAction(FGSPDFDocumentRef document, FGSPDFDocAActionType aaType);
    
/**
 * @brief This method is required for performing the page object's additional-action when opened or closed.
 *
 * @details This method will do nothing if no additional-action corresponding to the specified aaType exists.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] page				Reference to a PDF page.
 * @param[in] aaType	        The additional action type of a page. See definitions <b>FGSPDFDocAActionType</b>.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillDoPageAAction(FGSPDFDocumentRef document, FGSPDFPageRef page, FGSPDFDocAActionType aaType);
    
/**
 * @brief You can call this member function when the mouse cursor moves. 
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] page				Reference to a PDF page. Returned by ::FGSPDFPageLoadPage.
 * @param[in] eventflag			Indicates the status of various virtual keys, default is 0. See definitions <b>FWLEventType</b>.
 * @param[in] page_x			Specifies the x-coordinate of the cursor in PDF user space. 
 * @param[in] page_y			Specifies the y-coordinate of the cursor in PDF user space.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillOnMouseMove(FGSPDFDocumentRef document, FGSPDFPageRef page, FWLEventType eventflag, Float32 page_x, Float32 page_y);
    
/**
 * @brief You can call this member function when the user presses the left mouse button.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] page				Reference to a PDF page. Returned by ::FGSPDFPageLoadPage.
 * @param[in] eventflag			Indicates the status of various virtual keys, default is 0. See definitions <b>FWLEventType</b>. 
 * @param[in] page_x			Specifies the x-coordinate of the cursor in PDF user space. 
 * @param[in] page_y			Specifies the y-coordinate of the cursor in PDF user space.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillOnMouseDown(FGSPDFDocumentRef document, FGSPDFPageRef page, FWLEventType eventflag, 
                                      Float32 page_x, Float32 page_y);
    
/**
 * @brief You can call this member function when the user releases the left mouse button.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] page				Reference to a PDF page. Returned by ::FGSPDFPageLoadPage.
 * @param[in] eventflag			Indicates the status of various virtual keys, default is 0. See definitions <b>FWLEventType</b>. 
 * @param[in] page_x			Specifies the x-coordinate of the cursor in device. 
 * @param[in] page_y			Specifies the y-coordinate of the cursor in device.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillOnMouseUp(FGSPDFDocumentRef document, FGSPDFPageRef page, FWLEventType eventflag, 
                                    Float32 page_x, Float32 page_y);
    
/**
 * @brief You can call this member function when a non-system key is pressed. 
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] page				Reference to a PDF page. Returned by ::FGSPDFPageLoadPage.
 * @param[in] nKeyCode			Indicates whether various virtual keys are down. 
 * @param[in] eventflag			Indicates the status of various virtual keys, default is 0. See definitions <b>FWLEventType</b>.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillOnKeyDown(FGSPDFDocumentRef document, FGSPDFPageRef page, FWLVKeyCode nKeyCode, FWLEventType eventflag);
    
/**
 * @brief You can call this member function when a non-system key is released. 
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] page				Reference to a PDF page. Returned by ::FGSPDFPageLoadPage.
 * @param[in] nKeyCode			The virtual-key code of the given key.
 * @param[in] eventflag			Indicates the status of various virtual keys, default is 0. See definitions <b>FWLEventType</b>.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillOnKeyUp(FGSPDFDocumentRef document, FGSPDFPageRef page, FWLVKeyCode nKeyCode, FWLEventType eventflag);

/**
 * @brief You can call this member function to set text string to a focused text field, when is in the input status.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] page				Reference to a PDF page. Returned by ::FGSPDFPageLoadPage.
 * @param[in] wText				The input text string in UTF-16LE format.
 * @param[in] eventflag			Indicates the status of various virtual keys, default is 0. See definitions <b>FWLEventType</b>.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillOnSetFocusFieldValue(FGSPDFDocumentRef document, FGSPDFPageRef page, CFStringRef wText, FWLEventType eventflag);

/**
 * @brief Set the highlight color of specified or all the form fields in the document.
 *
 * @details When the parameter fieldType is set to zero, the highlight color will be applied to all the form fields in the 
 *			document.<br>
 *			Please refresh the client window to show the highlight immediately if necessary.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] fieldType			A 32-bit integer indicating the type of a form field, see enum definitions <b>FGSPDFFieldType</b>.
 * @param[in] color				The highlight color of the form field. Constructed by 0xxxrrggbb.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillSetFormFieldHighlightColor(FGSPDFDocumentRef document, SInt32 fieldType, UInt32 color);

/**
 * @brief Show Form Fill Highlight or not.
 *
 * @details Please refresh the client window to remove the highlight immediately if necessary.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] show				Show highlight or not.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillShowFormFieldHighlight(FGSPDFDocumentRef document, Boolean show);
    
/**
 * @brief Render FormFeilds(widgets) on a page to a device independent bitmap. 	
 *
 * @details This method is designed to only render FormFields on the page. 
 *			With '::FPDF_RENDER_ANNOT|::FPDF_RENDER_NOWIDGET' specified for flags, rendering functions (like ::FPDF_RenderPage_Start) will only render page contents and annotations without widgets to a bitmap.
 *			In order to implement the FormFill functions,Implementation should call this method after rendering functions finish rendering the page contents and annotations.
 *
 * @param[in] bitmapContext		Bitmap context reference can be created by ::CGBitmapContextCreate.							
 * @param[in] page				Reference to a PDF page. Returned by ::FGSPDFPageLoadPage .
 * @param[in] start_x			Left pixel position of the display area in the device coordinate.
 * @param[in] start_y			Top pixel position of the display area in the device coordinate.
 * @param[in] size_x			Horizontal size (in pixels) for displaying the page.
 * @param[in] size_y			Vertical size (in pixels) for displaying the page.
 * @param[in] rotate			Page orientation:<br>
 *								<ul>
 *								<li>0: normal.</li>
 *								<li>1: rotated 90 degrees clockwise.</li>
 *								<li>2: rotated 180 degrees.</li>
 *								<li>3: rotated 90 degrees counter-clockwise.</li>
 *								</ul>
 * @param[in] flags				0 means normal display. This can also be the combination of macro definitions <b>FGSPDFRenderFlag</b>.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillRender(CGContextRef bitmapContext, FGSPDFPageRef page, SInt32 start_x, SInt32 start_y, 
                             SInt32 size_x, SInt32 size_y, SInt32 rotate, FGSPDFRenderFlag flags);

/**
 * @brief Export the form data to a xml file
 *
 * @param[in] document			Reference to the interactive form.
 * @param[in] streamOut			Reference to a <b>::FGSFileStreamOutRef</b> object.   
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillExportFormDataToXML(FGSPDFDocumentRef document, FGSFileStreamOutRef streamOut);

/**
 * @brief Export the form data to a FDF file.
 *
 * @param[in] document			Reference to the interactive form.
 * @param[in] pdfPath			The File path of this document.
 * @param[in] simpleFileSpec	Whether to include or exclude the form fields.
 * @param[in] streamOut			Reference to a <b>::FGSFileStreamOutRef</b> object.  
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet	FGSPDFFormFillExportFormDataToFDF(FGSPDFDocumentRef document, CFStringRef pdfPath, Boolean simpleFileSpec, FGSFileStreamOutRef streamOut);

/**
 * @brief Import the form data from a XML file.
 *
 * @param[in] document			Reference to the interactive form.
 * @param[in] streamIn			Reference to a <b>::FGSFileStreamInRef</b> object.
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFFormFillImportFormDataFromXML(FGSPDFDocumentRef document, FGSFileStreamInRef streamIn);

/**
 * @brief Import the form data from a XML file.
 *
 * @param[in] document			Reference to the interactive form.
 * @param[in] notify			Whether to do notifying.
 * @param[in] streamIn			Reference to a <b>::FGSFileStreamInRef</b> object.
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet	FGSPDFFormFillImportFormDataFromFDF(FGSPDFDocumentRef document, Boolean notify, FGSFileStreamInRef streamIn);
    
/**
 * @brief Get the count of specified fields.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] fieldname			The field name to be matched.<br>
 *								If this is empty, that means for all fields; otherwise the system will match the field name.<br>
 *								As the shortest string, for example, text1 will match text1.0, text1.2.0, etc. 
 *								But text1 will not match test10 or test11.1 . 		
 *
 * @return	The count of fields with specified field name to be matched. 
 *
 */
SInt32 FGSPDFFormFillCountFields(FGSPDFDocumentRef document, CFStringRef fieldname);
    
/**
 * @brief Get a form field.
 *
 * @param[in] document			Reference to a PDF document.
 * @param[in] fieldindex		The zero-based field index in the matched field array.
 * @param[in] fieldname			The field name to be matched.<br>
 *								If this is empty, that means for all fields; otherwise the system will match the field name.<br>
 *								As the shortest string, for example, text1 will match text1.0, text1.2.0, etc. 
 *								But text1 will not match test10 or test11.1 . 		
 *	
 * @return	A reference to the form field.
 *
 */
FGSPDFFormFieldRef FGSPDFFormFillGetField(FGSPDFDocumentRef document, SInt32 fieldindex, CFStringRef fieldname);

/**
 * @brief	Get the reference of the form field.
 *
 * @param[in] formControl		The reference to the form control.			
 * 
 * @return	A reference of the form field.
 */
FGSPDFFormFieldRef FGSPDFFormFillGetControlField(FGSPDFFormControlRef formControl);
   
/** 
 * @name FGSPDFFORMFILL Enumeration Types
 */
/**@{*/

/**
 * @brief Enum Definitions for Field Types.
 */
enum {
    /**  Unknown. */
    kFGSPDFFieldTypeUnknown         = 0,
    /**  Push button. */
    kFGSPDFFieldTypePushButton      = 1,
    /**  Check box. */
    kFGSPDFFieldTypeCheckBox        = 2,
    /**  Radio button. */
    kFGSPDFFieldTypeRadioButton     = 3,		
    /**  Combo box. */
    kFGSPDFFieldTypeComboBox        = 4,	
    /**  List box. */
    kFGSPDFFieldTypeListBox         = 5,		
    /**  Text field. */
    kFGSPDFFieldTypeTextField       = 6,
    /**  Signature. */
    kFGSPDFFieldTypeSignature       = 7,
};
/** @brief Alias of enumeration for field types. */
typedef UInt32 FGSPDFFieldType;  

/**
 * @brief Enum Definitions for common Form Field Flags.
 */
enum {
    /**  The field is read only and no editing is allowed. */
    kFGSPDFFieldFlagReadOnly        = 0x01,
    /**  The field will be exported by a submit-form action. */
    kFGSPDFFieldFlagRequired        = 0x02,
    /**  The field must not be exported by a submit-form action. */
    kFGSPDFFieldFlagNoExport        = 0x04,
};
/** @brief Alias of enumeration for common form field falgs. */
typedef UInt32 FGSPDFFieldFlag;
/**@}*/

/**
 * @name Additional flags for radio button fields.
 */
/*@{*/
/**
 * @brief For radio button only: if set, one radio button has to be selected at any time;
 * Otherwise, when the selected radio button is clicked, it will be turned off,
 * (leaving no radio button selected at this time).
 */
#define kFGSPDFFieldRadioFlagNoToggleOff	0x100
/**
 * @brief If set, radio buttons with same value in a field will be turned on or off
 * in unison (either all one, or all off). If cleared, all buttons are 
 * mutually exclusive.
 */
#define kFGSPDFFieldRadioFlagUnison			0x200
/*@}*/

/**
 * @name Additional flags for text fields.
 */
/*@{*/
    
/** @brief Multiple lines. */
#define kFGSPDFFieldTextFlagMultiLine		0x100
/** @brief This is a password field. Password shouldn't be displayed or exported. */
#define kFGSPDFFieldTextFlagPassword		0x200
/**
 * @brief Do not scroll (vertically for multi-line field, or horizontally for
 * single-line field). If the field is full, no more text is accepted.
 */
#define kFGSPDFFieldTextFlagNoScroll		0x400
/**
 * @brief If set, this field is arranged in a number of equally spaced positions
 * ("combs"), the number of positions is determined by MaxLen parameter.
 */
#define kFGSPDFFieldTextFlagComb			0x800
/*@}*/
    
/**
 * @name Additional flags for combo box fields.
 */
/*@{*/
/**
 * @brief (Meaningful only when kFGSPDFFieldComboFlagEdit flag is set): if set, the combo box
 * includes an editable text control, otherwise, it's only a drop list.
 */
#define kFGSPDFFieldComboFlagEdit           0x100
/*@}*/
    
/**
 * @name Additional flags for list box fields.
 */
/*@{*/
/** @brief If set, more than one items can be selected. */
#define kFGSPDFFieldListFlagMultiSelect     0x100
/*@}*/

/** 
 * @name FGSPDFFORMFILL Enumeration Types
 */
/**@{*/

/**
 * @brief 'Q' entry in Field dictionary which common to all fields containing variable text.
 * A code specifying the form of quadding (justification) to be used in displaying the text.
 */
enum {
    /**  invalidate.*/
    kFGSPDFFieldJustificationInvalid        = -1,
    /**  left-justified.*/
    kFGSPDFFieldJustificationLeft           = 0,
    /**  centered.*/
    kFGSPDFFieldJustificationCenter         = 1,
    /**  right-justified.*/
    kFGSPDFFieldJustificationRight          = 2,
};
/** @brief Alias of enumeration for formfield justified types. */
typedef UInt32 FGSPDFFieldJustification;  
/**@}*/
/**
 * @brief Get the form of quadding (justification) to be used in displaying the text..
 *
 * @param[in]  formfield		Reference to the form field.
 * 
 * @return	The form of quadding (justification) to be used in displaying the text.<br>
			See the enum defination <b>FGSPDFFieldJustification</b>.
 */
FGSPDFFieldJustification FGSPDFFormFillGetFieldJustification(FGSPDFFormFieldRef formfield);

/** 
 * @brief Get the field flags. 
 *
 * @param[in] formfield			Reference to the form field.		
 *
 * @return	The field flags. See definitions <b>FGSPDFFieldFlag</b>.
 */
FGSPDFFieldFlag FGSPDFFormFillGetFieldFlags(FGSPDFFormFieldRef formfield);

/** 
 * @brief Get the field type.
 *
 * @param[in] formfield			Reference to the form field.	 
 *
 * @return	The field type. See definitions <b>FGSPDFFieldType</b>.
 */
FGSPDFFieldType FGSPDFFormFillGetFieldType(FGSPDFFormFieldRef formfield);
    
/** 
 * @brief Get the full name of the field.
 *
 * @param[in] formfield			Reference to the form field.
 *
 * @return	The name string.
 */
CFStringRef FGSPDFFormFillCopyFieldFullName(FGSPDFFormFieldRef formfield);
    
/** 
 * @brief Get the value of the field.
 *
 * @param[in]		formfield	Reference to the form field.
 *
 * @return	The value string.
 */
CFStringRef FGSPDFFormFillCopyFieldValue(FGSPDFFormFieldRef formfield);
    
/**
 * @brief Set the value of the field. not applicable to non-unison radio box.
 *
 * @param[in] formfield			Reference to the form field.
 * @param[in] value				The input field value, UTF16-LE format, terminated by zero.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 * @note	
 *  <ul>
 *  <li>For a text field, the value is a text string;</li>
 *  <li>For a radio button or check box field, the value is the state of the selected button, <b>on</b> or <b>off</b>;</li>
 *  <li>For a list box field, the value is the value of the first selected item, if there's any;</li>
 *  <li>For a comb box field, the value is a text string.</li>
 *  </ul>
 */
FGSErrorRet FGSPDFFormFillSetFieldValue(FGSPDFFormFieldRef formfield, CFStringRef value);

/**
 * @brief Get the count of options.
 *
 * @param[in] formfield		Reference to the form field.
 *		
 * @return	The count of options.
 */
SInt32 FGSPDFFormFillCountFieldOptions(FGSPDFFormFieldRef formfield);

/**
 * @brief Get the label of specified option.
 *
 * @param[in] formfield		Reference to the form field.
 * @param[in] index			The zero-based option index.
 *
 * @return	A string buffer to receive unicode label string.
 */
CFStringRef FGSPDFFormFillCopyFieldOptionLabel(FGSPDFFormFieldRef formfield, SInt32 index); 

/**
 * @brief Get the value of specified option.
 *
 * @param[in] formfield		Reference to the form field.
 * @param[in] index			The zero-based option index.
 *
 * @return	A string buffer to receive unicode option value string.
 */
CFStringRef FGSPDFFormFillCopyFieldOptionValue(FGSPDFFormFieldRef formfield, SInt32 index);
    
#ifdef __cplusplus
};
#endif

#endif // __FGSPDFFORMFILL__
/**@}*/

